fix: resolve SKILL.md loading failure in Claude Code global scope (issue #5)#21
Open
cjxzdzh wants to merge 1 commit into
Open
fix: resolve SKILL.md loading failure in Claude Code global scope (issue #5)#21cjxzdzh wants to merge 1 commit into
cjxzdzh wants to merge 1 commit into
Conversation
Root causes fixed: 1. Removed non-standard 'allowed-tools' field not in Hermes skill schema 2. Added missing standard frontmatter fields: version, author, license, platforms 3. Restructured metadata to use hermes-standard metadata.hermes.tags structure 4. Replaced Markdown HR '---' with '***' to avoid YAML document-separator confusion when parsed by non-frontmatter-aware loaders These changes make the SKILL.md compliant with hermes-agent skill schema and resolve the loading failure reported in issue op7418#5 on Windows 10 + OpenCode.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Root Cause Analysis
The SKILL.md failed to load when placed in Claude Code's global skills directory on Windows 10 + OpenCode (issue #5). Investigation revealed two classes of issues:
1. Non-standard frontmatter fields
allowed-tools— not part of the Hermes skill schemaversion,author,license,platforms,metadata.hermes.tags— all required by the hermes-agent skill schema2. YAML document-separator ambiguity
The Markdown body used
---as horizontal rules (section separators). These---lines were interpreted as YAML document separators (---starts a new YAML document in a YAML stream), causing "expected a single document in the stream" errors when the file was parsed as a full YAML stream.Fix: Replaced all body
---horizontal rules with***(also renders as a horizontal rule in Markdown) to avoid YAML document-separator confusion.Changes
allowed-toolsfieldversion: 1.0.0,author,license: MIT,platforms: [linux, macos, windows]metadatato use hermes-standardmetadata.hermes.tagsandmetadata.hermes.related_skills---with***in the bodyVerification
safe_load()name,description(147 chars, within 1024 limit)Closes #5